Address AI-induced inefficiencies#1
Conversation
From https://lethain.com/make-no-assumptions/ > The author must be the first human in the loop for their output. The biggest cultural failure with harnesses is when you can tell that you–the recipient of a piece of work–are the first human in the loop reviewing it. You must set a cultural norm that the creator of a piece of content is always the first human in the loop before asking another human to review it. If you fail to set that cultural expectation, then you will quickly crush the remaining team with a high standard for quality reasoning, which will lead to a full destruction of your reasoning horizon. I switched from "reviewing" to "reading" since this could apply to all forms of written communication, like performance reviews. I added "and synthesized" to indicate that it's insufficient to simply review (look at) and validate (verify correctness, quality, appropriateness), the developer must go further and integrate the generated content into the larger context and their theories
"don't build" has always felt a bit prescriptive and constraining. I've found myself both (1) _not_ writing a script for fear of having to maintain it later, even though I probably should've written the throw-away tool instead of doing the thing manually, and (2) chafing at it and deciding "heck with it, I'm going to build the fragile thing anyway." The massive adoption of AI and Claude Code shifts the landscape, making it much cheaper to build throw-away scripts for specific uses. We shouldn't discourage this, for many reasons, but should avoid _promoting_ unmaintainable things to the trunk or main branch.
| - Don't build or rely on anything that you aren't willing and able to maintain | ||
| - Don't promote or rely on anything that you aren't willing and able to maintain |
There was a problem hiding this comment.
Might be worth defining build vs promote here in a different line?
There was a problem hiding this comment.
Agree, but I'd like to find a way to do it very succintly.
- "build" = create, which is incresingly worth doing, even with no intention to maintain it, if the use case is narrow and lifespan is tiny, since it's cheaper to do that via AI than ever before
- "promote" = increase the use (and therefore blast radius), as newly defined at the top of the page: promote to the main branch of a heavily used repository, share widely among multiple teams or users that may implicitly expect you to maintain it, etc.
I could just say "promote to the trunk" as an approximation, but worry that's too narrow?
There was a problem hiding this comment.
I think "promote to the trunk" would be too narrow, but I like your definitions.
Maybe could be done in an active fashion? I don't know how you feel about the "but" in the second line essentially appending to the first vs being a totally separate line. If separate, I think it needs slightly more context to properly differentiate it from build/create
- Make it easy to build and create software, even if the use case is narrow and the lifespan is tiny.
- But do not promote or rely on anything you aren't willing and able to maintain
- Existing bullets on maintaining software
| - Commit and push frequently | ||
| - Clear and comprehensive MR descriptions are far more important than individual commit messages | ||
| - Updating the MR description costs nothing, work on continuously improving it | ||
| - Focus on [why (and why not), not how](https://cbea.ms/git-commit/#why-not-how), providing context and [theory](https://pablo.rauzy.name/dev/naur1985programming.pdf) that isn't already visible in the diff |
There was a problem hiding this comment.
I find myself wanting this to be stronger. I still like the idea of writing for a reviewer/future person looking at such that they can build their own mental model without looking at the code
For posterity, here was the original line I sent you (admittedly, tone doesn't match most of what is in this document):
MR descriptions should accurately capture your understanding of the problem space and the solution taken in enough detail such that a reviewer can build their own mental model of the changeset before ever looking at the code
There was a problem hiding this comment.
Yeah, I was relying on the definitions embedded in those links that many people probably won't click. Could make the ask explicit first, and include the links as additional reading?
| - Focus on [why (and why not), not how](https://cbea.ms/git-commit/#why-not-how), providing context and [theory](https://pablo.rauzy.name/dev/naur1985programming.pdf) that isn't already visible in the diff | |
| - Present your understanding of the problem space and your solution's position within it, so the reviewer can build a mental model before looking at code | |
| - Focus on [why (and why not), not how](https://cbea.ms/git-commit/#why-not-how), providing context and [theory](https://pablo.rauzy.name/dev/naur1985programming.pdf) that isn't already visible in the diff |
2 participants
Adoption of AI coding harnesses like Claude Code risks eroding the team's efficiency through some nascent behaviors that are adjacent to and not quite addressed by this guide. Try to cover some observed misbehaviors with clear bullets, stopping well short of directly addressing proper and improper use of AI.